
/*
 * Copyright 2002-2021 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/*
 *版权所有2002-2021原作者。
 *
 *根据Apache许可证2.0版许可（“许可证”）；
 *除非符合许可证的规定，否则您不得使用此文件。
 *您可以在以下网址获取许可证副本：
 *
 *https://www.apache.org/licenses/LICENSE-2.0
 *
 *除非适用法律要求或书面同意，软件
 *根据许可证进行的分发是在“按原样”的基础上进行的，
 *无任何明示或暗示的保证或条件。
 *有关管理权限的特定语言，请参阅许可证和
 *许可证下的限制。
 */

package org.springframework.scheduling.annotation;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Repeatable;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import java.util.concurrent.TimeUnit;

import org.springframework.aot.hint.annotation.Reflective;
import org.springframework.scheduling.config.ScheduledTaskRegistrar;

/**
 * Annotation that marks a method to be scheduled. Exactly one of the
 * {@link #cron}, {@link #fixedDelay}, or {@link #fixedRate} attributes must be
 * specified.
 *
 * <p>The annotated method must expect no arguments. It will typically have
 * a {@code void} return type; if not, the returned value will be ignored
 * when called through the scheduler.
 *
 * <p>Processing of {@code @Scheduled} annotations is performed by
 * registering a {@link ScheduledAnnotationBeanPostProcessor}. This can be
 * done manually or, more conveniently, through the {@code <task:annotation-driven/>}
 * XML element or {@link EnableScheduling @EnableScheduling} annotation.
 *
 * <p>This annotation can be used as a <em>{@linkplain Repeatable repeatable}</em>
 * annotation.
 *
 * <p>This annotation may be used as a <em>meta-annotation</em> to create custom
 * <em>composed annotations</em> with attribute overrides.
 *
 * @author Mark Fisher
 * @author Juergen Hoeller
 * @author Dave Syer
 * @author Chris Beams
 * @author Victor Brown
 * @author Sam Brannen
 * @since 3.0
 * @see EnableScheduling
 * @see ScheduledAnnotationBeanPostProcessor
 * @see Schedules
 */
/**
 *标记要计划的方法的批注。正是其中之一
 *｛@link#cron｝、｛@link#fixedDelay｝或｛@link#fixedRate｝属性必须为
 *指定。
 *
 *<p>带注释的方法不能期望有任何参数。它通常会
 *｛@code void｝返回类型；否则，将忽略返回的值
 *当通过调度程序调用时。
 *
 *<p>｛@code@Scheduled｝注释的处理由执行
 *注册｛@link ScheduledAnnotationBeanPostProcessor｝。这可以是
 *手动完成，或者更方便地通过｛@code＜task:annotation-driven/＞｝
 *XML元素或｛@link EnableScheduling@EnableSchedung｝注释。
 *
 *<p>此注释可以用作<em>｛@linkplain Repeatable Repeatable｝</em>
 *注释。
 *
 *<p>此注释可以用作<em>元注释</em>以创建自定义
 *<em>使用属性重写组合注释</em>。
 *
 *@作者Mark Fisher
 *@作者于尔根·霍勒
 *@作者Dave Syer
 *@作者Chris Beams
 *@作者Victor Brown
 *@作者Sam Brannen
 *@自3.0起
 *@请参阅EnableScheduling
 *@请参阅ScheduledAnnotationBeanPostProcessor
 *@参见时间表
 */
@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Repeatable(Schedules.class)
@Reflective
public @interface Scheduled {

	/**
	 * A special cron expression value that indicates a disabled trigger: {@value}.
	 * <p>This is primarily meant for use with <code>${...}</code> placeholders,
	 * allowing for external disabling of corresponding scheduled methods.
	 * @since 5.1
	 * @see ScheduledTaskRegistrar#CRON_DISABLED
	 */
	/**
	 *一个特殊的cron表达式值，指示禁用的触发器：｛@value｝。
	 *<p>这主要用于<code>${…}</code>占位符，
	 *从而允许相应的调度方法的外部禁用。
	 *@自5.1起
	 *@见ScheduledTaskRegistrar#CRON_DISABLED
	 */
	String CRON_DISABLED = ScheduledTaskRegistrar.CRON_DISABLED;


	/**
	 * A cron-like expression, extending the usual UN*X definition to include triggers
	 * on the second, minute, hour, day of month, month, and day of week.
	 * <p>For example, {@code "0 * * * * MON-FRI"} means once per minute on weekdays
	 * (at the top of the minute - the 0th second).
	 * <p>The fields read from left to right are interpreted as follows.
	 * <ul>
	 * <li>second</li>
	 * <li>minute</li>
	 * <li>hour</li>
	 * <li>day of month</li>
	 * <li>month</li>
	 * <li>day of week</li>
	 * </ul>
	 * <p>The special value {@link #CRON_DISABLED "-"} indicates a disabled cron
	 * trigger, primarily meant for externally specified values resolved by a
	 * <code>${...}</code> placeholder.
	 * @return an expression that can be parsed to a cron schedule
	 * @see org.springframework.scheduling.support.CronExpression#parse(String)
	 */
	/**
	 *类似cron的表达式，将通常的UN*X定义扩展为包括触发器
	 *在第二天、分钟、小时、月份、月份和星期几。
	 *<p>例如，{@code“0***MON-FRI”}表示工作日每分钟一次
	 *（上半部分-第0秒）。
	 *<p>从左到右读取的字段解释如下。
	 *<ul>
	 *<li>秒</li>
	 *<li>分钟</li>
	 *<li>小时</li>
	 *<li>月的哪一天</li>
	 *<li>月</li>
	 *<li>星期几</li>
	 *</ul>
	 *<p>特殊值{@link#CRON_DISABLED“-”}表示禁用的CRON
	 *触发器，主要用于由
	 *<code>$｛…｝</code>占位符。
	 *@返回一个可以解析为cron计划的表达式
	 *@see.org.springframework.sscheduling.support.CronExpression#parse（字符串）
	 */
	String cron() default "";

	/**
	 * A time zone for which the cron expression will be resolved. By default, this
	 * attribute is the empty String (i.e. the server's local time zone will be used).
	 * @return a zone id accepted by {@link java.util.TimeZone#getTimeZone(String)},
	 * or an empty String to indicate the server's default time zone
	 * @since 4.0
	 * @see org.springframework.scheduling.support.CronTrigger#CronTrigger(String, java.util.TimeZone)
	 * @see java.util.TimeZone
	 */
	/**
	 *将解析cron表达式的时区。默认情况下，此
	 *属性是空字符串（即将使用服务器的本地时区）。
	 *@return一个被{@link java.util.TimeZone#getTimeZone（String）}接受的区域id，
	 *或一个空字符串，用于指示服务器的默认时区
	 *@自4.0起
	 *@参见org.springframework.scheducing.support.CronTrigger#CronTrigger（字符串，java.util.TimeZone）
	 *@见java.util.TimeZone
	 */
	String zone() default "";

	/**
	 * Execute the annotated method with a fixed period between the end of the
	 * last invocation and the start of the next.
	 * <p>The time unit is milliseconds by default but can be overridden via
	 * {@link #timeUnit}.
	 * @return the delay
	 */
	/**
	 *在
	 *上一次调用和下一次调用的开始。
	 *<p>默认情况下，时间单位为毫秒，但可以通过
	 *｛@link#timeUnit｝。
	 *@返回延迟
	 */
	long fixedDelay() default -1;

	/**
	 * Execute the annotated method with a fixed period between the end of the
	 * last invocation and the start of the next.
	 * <p>The time unit is milliseconds by default but can be overridden via
	 * {@link #timeUnit}.
	 * @return the delay as a String value &mdash; for example, a placeholder
	 * or a {@link java.time.Duration#parse java.time.Duration} compliant value
	 * @since 3.2.2
	 */
	/**
	 *在
	 *上一次调用和下一次调用的开始。
	 *<p>默认情况下，时间单位为毫秒，但可以通过
	 *｛@link#timeUnit｝。
	 *@以字符串值形式返回延迟&mdash；例如，占位符
	 *或符合{@linkjava.time.Duration#parsejava.time.Duation}的值
	 *@自3.2.2起
	 */
	String fixedDelayString() default "";

	/**
	 * Execute the annotated method with a fixed period between invocations.
	 * <p>The time unit is milliseconds by default but can be overridden via
	 * {@link #timeUnit}.
	 * @return the period
	 */
	/**
	 *在两次调用之间有一个固定的周期来执行带注释的方法。
	 *<p>默认情况下，时间单位为毫秒，但可以通过
	 *｛@link#timeUnit｝。
	 *@返回周期
	 */
	long fixedRate() default -1;

	/**
	 * Execute the annotated method with a fixed period between invocations.
	 * <p>The time unit is milliseconds by default but can be overridden via
	 * {@link #timeUnit}.
	 * @return the period as a String value &mdash; for example, a placeholder
	 * or a {@link java.time.Duration#parse java.time.Duration} compliant value
	 * @since 3.2.2
	 */
	/**
	 *在两次调用之间有一个固定的周期来执行带注释的方法。
	 *<p>默认情况下，时间单位为毫秒，但可以通过
	 *｛@link#timeUnit｝。
	 *@以字符串值形式返回句点&mdash；例如，占位符
	 *或符合{@linkjava.time.Duration#parsejava.time.Duation}的值
	 *@自3.2.2起
	 */
	String fixedRateString() default "";

	/**
	 * Number of units of time to delay before the first execution of a
	 * {@link #fixedRate} or {@link #fixedDelay} task.
	 * <p>The time unit is milliseconds by default but can be overridden via
	 * {@link #timeUnit}.
	 * @return the initial
	 * @since 3.2
	 */
	/**
	 *在第一次执行之前要延迟的时间单位数
	 *｛@link#fixedRate｝或｛@link#fixedDelay｝任务。
	 *<p>默认情况下，时间单位为毫秒，但可以通过
	 *｛@link#timeUnit｝。
	 *@返回首字母
	 *@自3.2起
	 */
	long initialDelay() default -1;

	/**
	 * Number of units of time to delay before the first execution of a
	 * {@link #fixedRate} or {@link #fixedDelay} task.
	 * <p>The time unit is milliseconds by default but can be overridden via
	 * {@link #timeUnit}.
	 * @return the initial delay as a String value &mdash; for example, a placeholder
	 * or a {@link java.time.Duration#parse java.time.Duration} compliant value
	 * @since 3.2.2
	 */
	/**
	 *在第一次执行之前要延迟的时间单位数
	 *｛@link#fixedRate｝或｛@link#fixedDelay｝任务。
	 *<p>默认情况下，时间单位为毫秒，但可以通过
	 *｛@link#timeUnit｝。
	 *@以字符串值的形式返回初始延迟&mdash；例如，占位符
	 *或符合{@linkjava.time.Duration#parsejava.time.Duation}的值
	 *@自3.2.2起
	 */
	String initialDelayString() default "";

	/**
	 * The {@link TimeUnit} to use for {@link #fixedDelay}, {@link #fixedDelayString},
	 * {@link #fixedRate}, {@link #fixedRateString}, {@link #initialDelay}, and
	 * {@link #initialDelayString}.
	 * <p>Defaults to {@link TimeUnit#MILLISECONDS}.
	 * <p>This attribute is ignored for {@linkplain #cron() cron expressions}
	 * and for {@link java.time.Duration} values supplied via {@link #fixedDelayString},
	 * {@link #fixedRateString}, or {@link #initialDelayString}.
	 * @return the {@code TimeUnit} to use
	 * @since 5.3.10
	 */
	/**
	 *用于{@link#fixedDelay}、{@link#fixedDelayString}、，
	 *｛@link#fixedRate｝、｛@link#fixedLateString｝和
	 *｛@link#initialDelayString｝。
	 *<p>默认为{@link时间单位#百万秒}。
	 *<p>｛@linkplain#cron（）cron表达式｝忽略此属性
	 *以及通过{@link#fixedDelayString}提供的{@linkjava.time.Duration}值，
	 *｛@link#fixedRateString｝或｛@link#initialDelayString｝。
	 *@返回要使用的｛@code TimeUnit｝
	 *@自5.3.10起
	 */
	TimeUnit timeUnit() default TimeUnit.MILLISECONDS;

}
